Skip to content

feat(base_msgs): add I8 base controller interfaces - #38

Draft
Evans-Kwashie wants to merge 24 commits into
mainfrom
feat/i8-base-controller-msgs
Draft

Evans-Kwashie wants to merge 24 commits into
mainfrom
feat/i8-base-controller-msgs

Conversation

@Evans-Kwashie

@Evans-Kwashie Evans-Kwashie commented Nov 11, 2026 •

Copy link
Copy Markdown

@BotshareAI for review

Summary

Adds the proposed I8 base-controller ROS 2 interface package, openamr_base_msgs, to ros2/openamr_base_msgs/.

The package defines five messages:

  • BaseStatus
  • BaseAuxStatus
  • BaseFault
  • BaseSubsystemStatus
  • BaseMotionConstraint

Also adds the package contract and README, 24 static interface regression tests, a Jazzy compatibility snapshot update, and the required STATE.md update.

The implementation follows the I8 rev4 proposal. It does not claim that the proposal or its unresolved contract decisions have been approved.

Work package

Issue #30 — I8 base-controller interfaces.

Integration Gate

Reuses the repository's existing ROS 2 Jazzy workspace, package discovery/build structure, compatibility snapshot tooling, central verification test runner, and downstream interface-install consumer.

Existing openamr_nav_msgs and openamr_ui_msgs packages remain unchanged.

The I8 package is added as a separate ROS 2 package under ros2/. No existing navigation or UI interfaces were replaced.

The compatibility snapshot was regenerated with the new package. Comparison confirmed that the existing navigation and UI package entries remained unchanged.

No firmware implementation, hardware interface, or safety-control implementation is introduced by this PR.

Tests

Added tests/test_base_msgs.py with 24 static contract checks covering message definitions, constants, fault identifiers, state semantics, lift validity/permit semantics, reset causes, ownership mapping, and prohibited interface additions.

The tests are integrated into the repository's central verification harness.

Reversion check: the repository verification gate includes a negative compatibility fixture that removes NavigationStatus.thresholds_id and confirms that the unchanged consumer rejects the incompatible interface with exit code 42.

Evidence

Base SHA: 14912e18ecb6473ebd7ef4a42c4bd1870b2023f6

Previously verified baseline head: ca44a258f056591484a75b2dca26f1868874053b\n\nCurrent head after review fixes, proposed lift-permit updates and Jazzy snapshot regeneration: e1fdfd28cb3a2869f9cdfff0cae3a2f0b0bed73c. Fresh verification of this updated head is pending.

python3 tools/run_verification_tests.py tests test_base_msgs.py
Ran 21 tests, OK

python3 tools/run_verification_tests.py tests test_compatibility.py
Ran 14 tests, OK

colcon build --base-paths ros2
Summary: 3 packages finished

bash tools/verify.sh
PASS: installed navigation and UI interfaces; contract version 1
PASS: late consumer received and validated retained navigation message
PASS: reverted interface rejected by unchanged consumer (expected exit 42)
PASS: all implemented verification stages

Evidence: .verification/run.LmU15W

Dependencies

The package uses ROS 2 Jazzy interface-generation and runtime dependencies declared in ros2/openamr_base_msgs/package.xml.

No new application-level runtime dependency is introduced.

For the full repository verification run, the local environment required the ROS Jazzy Cyclone DDS middleware package (ros-jazzy-rmw-cyclonedds-cpp) in addition to the existing Fast DDS middleware. This was an environment prerequisite for the DDS verification stage, not a dependency added to the I8 message package.

Decisions impact

  • None: no register value is stated, used or changed.
  • Consumer: uses or aligns with these entries, unchanged: BASE-CONTROLLER-GATES, BASE-CONTROLLER-IO, CHARGING, STOP-RELEASE, TELEMETRY-NOT-SAFETY-EVIDENCE, SAFETY-CHAIN-IO
  • Change: needs a new or changed decision; change request # (entry: )

This PR does not modify the organization decision register. The I8-specific message-schema and controller semantics remain proposed under I8 rev4. The package does not claim approval of the unresolved I8 decisions or implement the complete robot-level Resume, safety-chain or lift-interlock enforcement.

Decision-register classification requires confirmation against openAMRobot/.github decisions.yaml before submission. This PR does not modify that register or claim approval of the open I8 decisions.

Current ownership and interface status

The named producer/consumer ownership mapping is recorded in
ros2/openamr_base_msgs/CONTRACT.md.
I8 firmware/electrical producer: Evans-Kwashie; platform software consumer: skunal3318
(with Mohamed reviewing); UI consumer: panthera-momagdii; manipulation consumer and
authoritative ArmStatus producer: Brinex45 alongside panthera-momagdii. Diagnostics/logging
ownership remains unassigned.

The 13 November I8 review proposed a three-message first release
(BaseStatus, BaseAuxStatus, BaseFault). This branch currently contains five message
definitions. Mohamed and Anushka's positions are still required before deciding whether
BaseSubsystemStatus and BaseMotionConstraint remain. Note that BaseAuxStatus currently
uses BaseSubsystemStatus as the type of its reserved_inputs field; deferring that message
therefore also requires an explicit decision about that field.

The proposed lift_permit fields, denial-reason candidates and fail-closed contract have been added to
BaseAuxStatus/ CONTRACT.md. Still open: ArmStatus schema, freshness and STOWED joint-space
sign-off; numerical permit maximum age and refresh/consumer timeout; reason-code mapping;
sequence-wrap semantics; base-stopped evidence source; and CTL-017 CAN PDO/object-dictionary
mapping. These are not represented as approved or physically validated.

Safety impact

Telemetry and proposed interface contract only.

No E-stop, brake, contactor, watchdog, motor-enable, charge-inhibit, safety I/O, or actuator-control implementation is changed.

The proposed status, readiness and lift-permit fields are not safety evidence and do not establish a safety function. Ownership direction is recorded: I8 produces the permit and CTL-017 is the final local enforcement point. The exact CAN PDO/object-dictionary mapping and physical/bench validation remain open.

STATE.md

Updated in this PR.

Records the I8 implementation, local verification result, proposed contract status, and remaining validation limitations.

Not verified

  • Firmware integration and message consumption on the STM32H723 or CTL-017 controllers.
  • Physical robot integration and hardware testing.
  • Safety-chain, E-stop, brake, contactor, watchdog, and actuator validation.
  • Production acceptance or released binary validation.
  • Cross-version deployment compatibility.
  • Formal owner approval of the I8 rev4 proposal.
  • Resolution of the remaining I8 contract decisions, including first-release message scope, ArmStatus schema/freshness/STOWED sign-off, permit maximum-age/reason/sequence details, CTL-017 CAN mapping, and diagnostics/logging ownership.

The verification evidence is local ROS 2 Jazzy software evidence only.

AI disclosure

AI assistance was used for planning, code review, test integration guidance, documentation review, and verification interpretation. The author reviewed the changes, executed the commands, and is responsible for the submitted implementation.

Contribution terms

Signed-off-by: Evans Klenam Kwashie-Seyram <ekks2006@gmail.com>

@panthera-momagdii panthera-momagdii left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

REQUEST_CHANGES at exact head ca44a258f056591484a75b2dca26f1868874053b.

The implementation is a useful proposed package and the exact-head hosted evidence is green: ROS 2 Jazzy run 42941431287 and Repository quality run 42941431718. I inspected both logs: the workspace built 3 packages, 18 generated interfaces were available, 14 compatibility tests ran, the retained-message consumer checks passed, and the reverted-interface negative check returned the expected exit 42. This is hosted ROS 2 software evidence only, not firmware, hardware, safety-chain or physical acceptance.

Two concrete P2 items need correction:

  1. Align BaseAuxStatus.header.stamp with the frozen timestamp contract. CONTRACT.md says header.stamp is ROS time when available and diagnostic only; monotonic_us is the controller-local monotonic clock. The BaseAuxStatus comment currently says its header stamp is the base-controller monotonic time base, which conflicts with that contract and with BaseStatus.
  2. Complete the producer/consumer owner mapping required by issue #30. CONTRACT.md says owners are in the PR description, but the current description lists consumer components/repos without named owners or roles. Add the named producer and consumer owners (or link an explicit owner assignment) and make the statement accurate.

The Section 8 I8 decisions remain proposed, not accepted: notably the final message set, E-01-derived state semantics, fault registry IDs/lifecycle, measured/declared lift-position sources, and the robot lift-interlock owner/handshake. Keep the PR Draft and the contract Proposed until those owners resolve the decisions. This review does not approve a firmware implementation, lift interlock, safety function, or physical acceptance.

|---|---|---|---|
| `/base/status` | `BaseStatus` | base-controller firmware (Teensy Gate A, STM32H723ZG Gate B), [openamr-platform-fw#10](https://github.com/openAMRobot/openamr-platform-fw/issues/10) | `navigation_status_node.py` in openamr-platform-sw, operator UI (openamrobot-ui #54), manipulation (openamrobot-manipulation #7), diagnostics, logging, tests |
| `/base/aux_status` | `BaseAuxStatus` | base-controller firmware, relayed from the lift node CTL-017 over CAN3 ([openamr-platform-fw#12](https://github.com/openAMRobot/openamr-platform-fw/issues/12), D17) | same as above |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Issue #30's Done-when requires producers and consumers to be listed with owners. The current PR description lists consumer components/repositories but does not name the producer or consumer owners/roles, so this sentence is not currently true. Please add an explicit owner/role mapping for the firmware producer and each downstream consumer (platform-sw, UI, manipulation, diagnostics/logging as applicable), or link the agreed assignments, then keep this statement accurate.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated ros2/openamr_base_msgs/CONTRACT.md with the named ownership confirmations recorded in this PR: I8 producer (Evans-Kwashie), platform software consumer (skunal3318; Mohamed reviewing), UI consumer (panthera-momagdii), and manipulation consumer/authoritative arm-status producer (Brinex45 alongside panthera-momagdii). The PR description now links to that mapping. Diagnostics/logging ownership is still explicitly TBD, so I am leaving this thread open until that remaining owner is assigned.

Copy link
Copy Markdown

Owner-decision follow-up at head ca44a25.

The new #20/#30 direction proposes an explicit base-produced lift_permit. This PR's BaseAuxStatus still carries lift telemetry only, and its comment says the interlock owner and handshake are undecided. The message has sequence and boot identity, but no permit field or permit-validity/withdrawal semantics.

Please add an explicit permit field or a dedicated message only after the owner confirms the wire contract. It needs a defined producer, validity/freshness, sequence and boot-ID behaviour, and fail-closed withdrawal semantics for the CTL-017 consumer. Keep this Draft; the ROS 2 message build does not verify the firmware or bench path.

Signed-off-by: Evans Klenam Kwashie-Seyram <ekks2006@gmail.com>
@Evans-Kwashie
Evans-Kwashie force-pushed the feat/i8-base-controller-msgs branch from f2adf80 to 81deda4 Compare November 15, 2026 11:02
@Evans-Kwashie

Copy link
Copy Markdown
Author

Hi @skunal3318, @Brinex45, @panthera-momagdii,

I'm following up on ownership for the I8 base-controller interfaces in PR #38.

The package implementation is in place and CI is passing. Before we can finalise the contract, I need to confirm the accountable owners for the producer and downstream consumers.

Based on the repository ownership files, could you please confirm the following assignments?

Responsibility Proposed owner / confirmation needed
Firmware producer — openamr-platform-fw @Evans-Kwashie
Platform software consumer — openamr-platform-sw @skunal3318 / @panthera-momagdii
UI consumer — openamrobot-ui @panthera-momagdii
Manipulation consumer — openamrobot-manipulation @Brinex45 / @panthera-momagdii
Diagnostics and logging Owner still to be confirmed

Please correct any assignment that is inaccurate and identify the accountable person where ownership is still unassigned.

There is also an outstanding cross-repository decision concerning the lift-permit interface:

  • The base controller is the authoritative producer of lift_permit.
  • The manipulation side must provide the authoritative arm-status information.
  • CTL-017 must enforce the permit locally and fail closed when it is missing, stale, invalid, or withdrawn.

Could the relevant owners confirm the arm-status ownership and the remaining interface responsibilities, including freshness and withdrawal behaviour?

I'll update CONTRACT.md once these assignments and decisions are confirmed. The PR and contract will remain Draft/Proposed in the meantime.

Thanks.

@Brinex45

Copy link
Copy Markdown

Thanks for clarifying the ownership assignments.

I confirm my involvement as the manipulation-side consumer owner for openamrobot-manipulation, alongside @panthera-momagdii.

From the manipulation side, I will take responsibility for the integration of the I8 interfaces and the authoritative arm-status information required by the lift interlock.

For the lift interlock, I agree that:

  • Manipulation publishes validated measured arm status through a separate ArmStatus interface.
  • The message includes publisher boot identifier and sequence number.
  • Build 1 supports only the STOWED safe configuration.
  • Invalid, stale, unavailable, or inconsistent feedback from either arm must result in a fail-closed status.
  • I8 remains the sole producer of lift_permit, while CTL-017 remains responsible for local permit enforcement.

I'd suggest keeping the exact ArmStatus schema, freshness threshold, and STOWED joint-space definition as explicit cross-repository contract decisions before finalizing the interface.

I can coordinate the manipulation-side interface and consumer implementation once these details are agreed.

@skunal3318

Copy link
Copy Markdown
Member

Confirming: I'm the accountable owner for the platform software consumer side (openamr-platform-sw), alongside Mohamed on review.

On the lift-interlock framing, I'm aligned with what Brinex45 laid out:

  • I8 is the sole producer of lift_permit; CTL-017 does the local enforcement.
  • Manipulation publishes the authoritative ArmStatus (separate message, publisher boot ID + sequence number).
  • Build 1 only supports STOWED as a safe configuration - nothing else is defined yet.
  • Any missing, stale, unavailable, or inconsistent feedback from either side has to fail closed, no exceptions.

Agreed on locking the exact ArmStatus schema, the freshness threshold, and the STOWED joint-space definition as their own explicit contract decisions before this leaves Draft - those three need sign-off from whoever owns the joint-space definition on the manipulation side, not just a general agreement on direction.

One thing still open from Mohamed's 11 Nov review that I want flagged again before this moves out of Draft: BaseAuxStatus still only carries lift telemetry, no explicit lift_permit field or permit-validity/withdrawal semantics. That needs to land before the platform-sw consumer side can actually implement against this.

Once the schema/freshness/STOWED decisions and the lift_permit field are nailed down, I can start on the platform-sw consumer implementation.

Copy link
Copy Markdown
Author

Thanks, @Brinex45 and @skunal3318 — your replies clarify the cross-repository ownership and the intended lift-interlock direction.

I’m recording the current working position from the I8 firmware/electrical side as follows:

  • I8 is the sole producer of lift_permit.
  • Manipulation owns the authoritative, validated ArmStatus producer and its interface.
  • CTL-017 remains responsible for local permit enforcement.
  • Platform software owns its consumer integration.
  • Build 1 recognises STOWED as the only defined safe arm configuration.
  • Missing, stale, unavailable or inconsistent arm feedback must fail closed.

There are still a few decisions to close before I update the contract:

  1. First-release message scope: PR feat(base_msgs): add I8 base controller interfaces #38 currently contains five messages: BaseStatus, BaseAuxStatus, BaseFault, BaseSubsystemStatus and BaseMotionConstraint. The 13 November I8 review proposed a three-message set: the first three only. @panthera-momagdii, could you help confirm the decision owners' position on whether BaseSubsystemStatus and BaseMotionConstraint remain in this release or are deferred? I don't want to remove either message or treat the five-message set as approved without that decision.

  2. ArmStatus contract: @Brinex45, please coordinate the manipulation-side definition of the exact ArmStatus schema, freshness threshold and STOWED joint-space definition, including sign-off from the person accountable for the joint-space definition. The publisher boot ID and sequence number, and fail-closed handling, should be reflected in that contract.

  3. Lift-permit contract: I8 will define the lift_permit representation and its validity, freshness, sequence, boot/restart and withdrawal semantics in BaseAuxStatus. The CTL-017 consumer must reject a missing, stale, invalid, repeated/out-of-sequence or withdrawn permit, and a permit from before either controller restarted. @skunal3318, please confirm this covers the platform-software consumer requirements, or identify anything else it needs.

  4. Diagnostics/logging ownership: This is still unassigned in the ownership mapping. @skunal3318 and @panthera-momagdii, could you identify the accountable owner or point me to the agreed assignment?

I’ll keep PR #38 Draft and the contract Proposed while these decisions are open. Once the message scope and cross-repository interface details are confirmed, I’ll update CONTRACT.md, the message definitions and the corresponding regression tests.

Thanks.

Evans-Kwashie commented Nov 17, 2026 •

Copy link
Copy Markdown
Author

Following up on the first-release scope before I change the package contents.

The 13 November I8 review proposes three messages only: BaseStatus, BaseAuxStatus and BaseFault. PR #38 currently contains five definitions, including BaseSubsystemStatus and BaseMotionConstraint.

Mohamed and Anushka: please record your positions on whether the two additional message types are required in Build 1 or should be deferred.

There are nested-type dependencies that must be decided at the same time:

  • BaseStatus.subsystems uses BaseSubsystemStatus[<=16].
  • BaseStatus.constraints uses BaseMotionConstraint[<=8].
  • BaseAuxStatus.reserved_inputs uses BaseSubsystemStatus[<=8].

If the decision is to ship only three message types, we need an explicit decision to remove or replace those fields (and update their consumers/tests), rather than simply deleting the two message files. If the nested fields are required, the corresponding message types must remain in the package.

I will not delete either message or claim the three-message scope is approved until the decision owners' positions are recorded.

Copy link
Copy Markdown
Author

Implementation update on PR #38:

  • Corrected the BaseAuxStatus.header.stamp comment and added a static consistency check; the timestamp review thread is now resolved.
  • Updated CONTRACT.md with the ownership confirmations recorded by Brinex45 and S.Kunal. Diagnostics/logging ownership remains explicitly TBD, so the ownership review thread remains open.
  • Added proposed lift_permit, lift_permit_reason_code and lift_permit_max_age_ms fields to BaseAuxStatus. The existing boot_id and sequence identify the producer boot and publication order. Added proposed denial-reason values and fail-closed/restart/withdrawal semantics.
  • Documented the separate manipulation-owned bimanual ArmStatus dependency and its required measured-feedback, motion, validity, session and sequence information. I have also requested the detailed schema/freshness/STOWED sign-off in manipulation issue #7.
  • Updated the Jazzy compatibility snapshot, regression tests, README and STATE.md.

Still open: Mohamed and Anushka's positions on three versus five messages (including the BaseSubsystemStatus nested-type dependency), diagnostics/logging owner, exact ArmStatus freshness and approved STOWED joint-space, permit maximum age/refresh timeout, sequence-wrap semantics, base-stopped evidence validation, and CTL-017 CAN PDO/OD mapping.

The fields and semantics remain Proposed. PR #38 remains Draft. Hosted verification is running on the latest head.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants